MPWaitOnQueue

MPWaitOnQueue
Header:	Multiprocessing.h		Carbon status:	Supported

Obtains a message from a specified message queue.

OSStatus MPWaitOnQueue (
    MPQueueID queue, 
    void **param1, 
    void **param2, 
    void **param3, 
    Duration timeout
);

queue: The ID of the message queue from which to receive the notification.
param1: A pointer to a 32-bit variable. On return, this variable contains the first 32-bits of the notification message. Pass NULL if you do not need this portion of the message.
param2: A pointer to a 32-bit variable. On return, the variable contains the second 32-bits of the notification message. Pass NULL if you do not need this portion of the message.
param3: A pointer to a 32-bit variable. On return, the variable contains the third 32-bits of the notification message. Pass NULL if you do not need this portion of the message.
timeout: The time to wait for a notification before timing out. See “Timer Duration Constants” for a list of constants you can use to specify the wait interval.

function result: A result code.

DISCUSSION

This function receives a message from the specified message queue. If no messages are currently available, the timeout specifies how long the function should wait for one. Tasks waiting on the queue are handled in a first in, first out manner; that is, the first task to wait on the queue receives the message from the MPNotifyQueue call.

After calling this function, when a message appears, it is removed from the queue and the three fields, param1, param2, and param3 are set to the values specified by the message text. Note these parameters are pointers to variables to be set with the message text.

If you call this function from a cooperative task, you should specify only kDurationImmediate for the timeout length; other waits will cause the task to block.

Also see the function MPNotifyQueue.

VERSION NOTES

Introduced with Multiprocessing Services 1.0.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when MPLibrary 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by MPLibrary 1.0 and later.